Structures are a compound value type: a series of fields are grouped together as a single block of data storage. You can control the size and order of the fields, so you can declare a structure in REALbasic to match a structure defined by some external library or as part of some binary file format or communications protocol. A structure can thus provide a convenient alternative to the MemoryBlock.
You might also use Structure when porting a Visual Basic application to REALbasic; it is very similar in concept and syntax to Visual Basic's "Type" feature (also known as a "UDT").
Structures are a value type, like an integer or a color, not a reference type like an object or an array. When you assign an object value to an object variable, you copy a reference to the object data; when you assign a structure value to a structure variable, you copy the entire contents of the structure. When you pass a structure as a parameter ByVal, the whole contents of the structure are copied; when you pass a structure ByRef, obviously the callee ends up modifying the caller's original structure instead.
The New operator does not apply to structures. When you create an array of structures, each element is an actual value (not a reference, like it would be with an array of objects). You can use the same dot syntax to access structure fields as you would use to access object properties, but when you use dot syntax with a structure, you are manipulating the structure variable itself, not a reference to data somewhere else.
Structures live in modules. Open a module and select Project > Add > Structure (you can customize the command bar and add this command if you use it frequently). A structure has a name and a list of fields, and can be global or private.
Click the plus button in the field list to create a new field, then type in the declaration. The field declaration syntax is basically the same as you'd use on a Dim statement or in a property declaration:
field As type
Like a property or local variable, field names must be simple identifiers and must be unique within the field.
Structure fields can be defined as arrays, using the usual syntax:
field(ubound) As type
Arrays in structure fields are not the same as normal arrays; they represent a fixed chunk of storage inside the structure, not a dynamic object that can be passed around and manipulated. Structure field arrays cannot be resized, cannot be assigned, and do not support the array methods.
Strings also have a special syntax and behavior inside a structure:
field As String * size
A string in a structure is a simple array of bytes. It has a fixed size and knows nothing about text encodings. Just as you convert text to a specific encoding when writing it to a file or a socket, and define it to the encoding you know it must have when reading it back in, you must convert strings to a specific encoding when you assign them to a structure and define them to the correct encoding when reading them back out.
Structure fields can contain any of the simple value types, but cannot contain objects. The editor will show you the size and location of each field, so that you can match your structure up exactly with an external data format.
Once you've defined a structure, you can use it in almost any context where you would use any other datatype. You can define an object or module property as a structure; you can declare a method parameter as a structure; you can even embed one structure as a field in another. Variants, however, cannot contain structures (try storing the StringValue instead), and you cannot return a structure from a method or event (try passing it as a ByRef parameter instead).
In addition to the fields you define, structures contain three built-in items:
.Size
This constant returns the total size of the structure in bytes.
.StringValue(littleEndian As Boolean)
This accessor pair lets you treat the structure as a string, which is useful for copying structures into and out of MemoryBlocks, for reading and writing structures to files, and for transmitting structures through sockets. You must pass in the desired endianness, which should match the LittleEndian property on the MemoryBlock on BinaryStream; StringValue will convert the structure's fields to or from the appropriate endianness as necessary.
